<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Back up a cluster’s security configuration | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="backup-cluster.html" title="Back up a cluster">
<link rel="prev" href="backup-cluster-configuration.html" title="Back up a cluster’s configuration">
<link rel="next" href="restore-security-configuration.html" title="Restore a cluster’s security configuration">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="high-availability.html">Set up a cluster for high availability</a></span>
»
<span class="breadcrumb-link"><a href="backup-cluster.html">Back up a cluster</a></span>
»
<span class="breadcrumb-node">Back up a cluster’s security configuration</span>
</div>
<div class="navheader">
<span class="prev">
<a href="backup-cluster-configuration.html">« Back up a cluster’s configuration</a>
</span>
<span class="next">
<a href="restore-security-configuration.html">Restore a cluster’s security configuration »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="security-backup"></a>Back up a cluster’s security configuration<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/high-availability/backup-and-restore-security-config.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>

<p>Security configuration information resides in two places:
<a class="xref" href="security-backup.html#backup-security-file-based-configuration" title="Back up file-based security configuration">files</a> and
<a class="xref" href="security-backup.html#backup-security-index-configuration" title="Back up index-based security configuration">indices</a>.</p>
<h4>
<a id="backup-security-file-based-configuration"></a>Back up file-based security configuration<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/high-availability/backup-and-restore-security-config.asciidoc">edit</a>
</h4>
<p>Elasticsearch security features are configured using the <a class="xref" href="security-settings.html" title="Security settings in Elasticsearch"><code class="literal">xpack.security</code> namespace</a> inside the <code class="literal">elasticsearch.yml</code> and
<code class="literal">elasticsearch.keystore</code> files. In addition there are several other
<a class="xref" href="security-files.html" title="Security files">extra configuration files</a> inside the same <code class="literal">ES_PATH_CONF</code>
directory. These files define roles and role mappings and configure the
<a class="xref" href="file-realm.html" title="File-based user authentication">file realm</a>. Some of the
settings specify file paths to security-sensitive data, such as TLS keys and
certificates for the HTTP client and inter-node communication and private key files for
<a class="xref" href="security-settings.html#ref-saml-settings" title="SAML realm settings">SAML</a>, <a class="xref" href="security-settings.html#ref-oidc-settings" title="OpenID Connect realm settings">OIDC</a> and the
<a class="xref" href="security-settings.html#ref-kerberos-settings" title="Kerberos realm settings">Kerberos</a> realms. All these are also stored inside
<code class="literal">ES_PATH_CONF</code>; the path settings are relative.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>The <code class="literal">elasticsearch.keystore</code>, TLS keys and SAML, OIDC, and Kerberos
realms private key files require confidentiality. This is crucial when files
are copied to the backup location, as this increases the surface for malicious
snooping.</p>
</div>
</div>
<p>To back up all this configuration you can use a <a class="xref" href="backup-cluster-configuration.html" title="Back up a cluster’s configuration">conventional file-based backup</a>, as described in the previous section.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
File backups must run on every cluster node.
</li>
<li class="listitem">
File backups will store non-security configuration as well. Backing-up
only security features configuration is not supported. A backup is a
point in time record of state of the complete configuration.
</li>
</ul>
</div>
</div>
</div>
<h4>
<a id="backup-security-index-configuration"></a>Back up index-based security configuration<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/high-availability/backup-and-restore-security-config.asciidoc">edit</a>
</h4>
<p>Elasticsearch security features store system configuration data inside a
dedicated index. This index is named <code class="literal">.security-6</code> in the Elasticsearch 6.x versions and
<code class="literal">.security-7</code> in the 7.x releases. The <code class="literal">.security</code> alias always points to the
appropriate index. This index contains the data which is not available in
configuration files and <span class="strong strong"><strong>cannot</strong></span> be reliably backed up using standard
filesystem tools. This data describes:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
the definition of users in the native realm (including hashed passwords)
</li>
<li class="listitem">
role definitions (defined via the <a class="xref" href="security-api-put-role.html" title="Create or update roles API">create roles API</a>)
</li>
<li class="listitem">
role mappings (defined via the
<a class="xref" href="security-api-put-role-mapping.html" title="Create or update role mappings API">create role mappings API</a>)
</li>
<li class="listitem">
application privileges
</li>
<li class="listitem">
API keys
</li>
</ul>
</div>
<p>The <code class="literal">.security</code> index thus contains resources and definitions in addition to
configuration information. All of that information is required in a complete
security features backup.</p>
<p>Use the <a class="xref" href="modules-snapshots.html" title="Snapshot module">standard Elasticsearch snapshot functionality</a> to backup
<code class="literal">.security</code>, as you would for any <a class="xref" href="backup-cluster-data.html" title="Back up a cluster’s data">other data index</a>.
For convenience, here are the complete steps:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Create a repository that you can use to backup the <code class="literal">.security</code> index.
It is preferable to have a <a class="xref" href="security-backup.html#backup-security-repos" title="Controlling access to the backup repository">dedicated repository</a> for
this special index. If you wish, you can also snapshot the system indices for other Elastic Stack components to this repository.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_snapshot/my_backup
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1168.console"></div>
<p>The user calling this API must have the elevated <code class="literal">manage</code> cluster privilege to
prevent non-administrators exfiltrating data.</p>
</li>
<li class="listitem">
<p>Create a user and assign it only the built-in <code class="literal">snapshot_user</code> role.</p>
<p>The following example creates a new user <code class="literal">snapshot_user</code> in the
<a class="xref" href="native-realm.html" title="Native user authentication">native realm</a>, but it is not important which
realm the user is a member of:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/user/snapshot_user
{
  "password" : "secret",
  "roles" : [ "snapshot_user" ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1169.console"></div>
</li>
<li class="listitem">
<p>Create incremental snapshots authorized as <code class="literal">snapshot_user</code>.</p>
<p>The following example shows how to use the create snapshot API to backup
the <code class="literal">.security</code> index to the <code class="literal">my_backup</code> repository:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_snapshot/my_backup/snapshot_1
{
  "indices": ".security",
  "include_global_state": true <a id="CO455-1"></a><i class="conum" data-value="1"></i>
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1170.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO455-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>This parameter value captures all the persistent settings stored in the
global cluster metadata as well as other configurations such as aliases and
stored scripts. Note that this includes non-security configuration and that it complements but does not replace the
<a class="xref" href="backup-cluster-configuration.html" title="Back up a cluster’s configuration">filesystem configuration files backup</a>.</p>
</td>
</tr>
</table>
</div>
</li>
</ol>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>The index format is only compatible within a single major version,
and cannot be restored onto a version earlier than the version from which it
originated. For example, you can restore a security snapshot from 6.6.0 into a
6.7.0 cluster, but you cannot restore it to a cluster running Elasticsearch 6.5.0 or 7.0.0.</p>
</div>
</div>
<h5>
<a id="backup-security-repos"></a>Controlling access to the backup repository<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/high-availability/backup-and-restore-security-config.asciidoc">edit</a>
</h5>
<p>The snapshot of the security index will typically contain sensitive data such
as user names and password hashes. Because passwords are stored using
<a class="xref" href="security-settings.html#hashing-settings" title="User cache and password hash algorithms">cryptographic hashes</a>, the disclosure of a snapshot would
not automatically enable a third party to authenticate as one of your users or
use API keys. However, it would disclose confidential information.</p>
<p>It is also important that you protect the integrity of these backups in case
you ever need to restore them. If a third party is able to modify the stored
backups, they may be able to install a back door that would grant access if the
snapshot is loaded into an Elasticsearch cluster.</p>
<p>We recommend that you:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Snapshot the <code class="literal">.security</code> index in a dedicated repository, where read and write
access is strictly restricted and audited.
</li>
<li class="listitem">
If there are indications that the snapshot has been read, change the passwords
of the users in the native realm and revoke API keys.
</li>
<li class="listitem">
If there are indications that the snapshot has been tampered with, do not
restore it. There is currently no option for the restore process to detect
malicious tampering.
</li>
</ul>
</div>
</div>
<div class="navfooter">
<span class="prev">
<a href="backup-cluster-configuration.html">« Back up a cluster’s configuration</a>
</span>
<span class="next">
<a href="restore-security-configuration.html">Restore a cluster’s security configuration »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
